nice_things/async/Future_racer.sh

Future_racer is a pseudo-class used internally by some functions in the Future class to race Futures against each other. It is the backbone of asynchronous functions like await_all_race, await_any and await_first.

The functions in this module are lower-level than the functions in the Future class. Unless you need the extra async flexibility of Future_racer, you should prefer the higher-level functions of the Future class instead.

The Future_racer API is a pseudo-class, with a constructor and destructor functions, but unlike a real class, only a single instance can exist at a time. The pseudo-object is an iterator, with only a next method. What is special about this iterator is that it picks Futures from the list asynchronously, in the order they settle.

Usage examples

Future_racer_new "$future1" "$future2" "$future3"
while Future_racer_next future status; do
	: # Check "$status" and/or do something with "$future"
done
Future_racer_destructor

Future_racer_destructor

Since 0.3.0 · Source

import "{ Future_racer_destructor }" from nice_things/async/Future_racer.sh

Synopsis
Future_racer_destructor

Configuration
–

Description
Clear all data associated with the racer pseudo-object.

Options
–

Operands
–

Stdin
–

Stdout
–

Stderr
–

Exit status
0: Successful completion.

Abort
–

Usage examples

Future_racer_destructor

Future_racer_new

Since 0.3.0 · Source

import "{ Future_racer_new }" from nice_things/async/Future_racer.sh

Synopsis
Future_racer_new <&future>…

Configuration
–

Description
Create a new racer pseudo-object.

Options
–

Operands
<&future>: Reference to a Future object.

Stdin
–

Stdout
–

Stderr
–

Exit status

• 0: Successful completion.
• 12: Invalid reference (abort).

Abort
Aborts if reference <&future> is invalid.

Usage examples

Future_racer_new "$future1" "$future2" "$future3"

Future_racer_next

Since 0.3.0 · Source

import "{ Future_racer_next }" from nice_things/async/Future_racer.sh

Synopsis
Future_racer_next [<out_var>] [<out_status>]

Configuration
–

Description
Await the next Future to settle. A reference to the Future is assigned to <out_var>, and its status code is assigned to <out_status>.

Options
–

Operands

• <out_var>: Output variable; a reference to the Future will be written to this variable.
• <out_status>: Output variable; the Future's status code will be written to this variable.

Stdin
–

Stdout
–

Stderr
log_error.

Exit status

• 0: Next Future retrieved.
• 1: Iteration finished.

Abort
–

Usage examples

Future_racer_next future status